/*
 * Copyright (C) 2009 Dimitrios C. Michalakos
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
package com.cs.util.db.ioc;

import com.cs.util.db.ioc.IOCException;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.sql.SQLException;

/**
 * IOController can be used for creating Input-Output controllers for database columns.
 * @author dimitris@jmike.gr
 */
public interface IOController {

    /**
     * Returns the id of this controller.
     * @return
     */
    public String getId();

    /**
     * Returns the label of this controller.
     * @return
     */
    public String getLabel();

    /**
     * Returns the table name of this controller.
     * @return
     */
    public String getTableName();

    /**
     * Returns the column name of this controller.
     * @return
     */
    public String getColumnName();

    /**
     * Returns the value of the controller's column at the specified row as a String.
     * @param rs the resultset containing the current row position and the field's value.
     * @return
     */
    public String getValue(ResultSet rs);

    /**
     * Sets the default value of this controller.
     * @param defaultValue the value.
     * @throws IOCException
     */
    public void setDefaultValue(String defaultValue) throws IOCException;

    /**
     * Returns the default value of this controller.
     * @return
     */
    public String getDefaultValue();

    /**
     * Sets an input lock for this controller.
     * When an input lock is set, the controller cannot except different values.
     * @param lockValue the value.
     * @throws IOCException
     */
    public void setInputLock(String lockValue) throws IOCException;

    /**
     * Set the value of the designated parameter in the specified PreparedStatement.
     * @param ps an object that represents a precompiled SQL statement.
     * @param parameterIndex the first parameter in the PreparedStatement is 1, the second is 2, ...
     * @param value the value of the parameter.
     * @throws java.sql.SQLException
     * @throws IOCException
     */
    public void setParameterValue(PreparedStatement ps, int parameterIndex, String value) throws SQLException, IOCException;

    /**
     * Returns the value of the controller's column at the specified row as a URL encoded String.
     * @param rs the resultset containing the current row position and the field's value.
     * @return
     */
    public String getURLEncodedValue(ResultSet rs);

    /**
     * Returns the value of the controller's column at the specified row as a String to be used in a Xhtml table.
     * @param rs the resultset containing the current row position and the field's value.
     * @return
     */
    public String getXhtmlTableData(ResultSet rs);

    /**
     * Returns a Xhtml form element for the controller's column.
     * @param rs the resultset containing the current row position and the field's value.
     * @param isEmpty a boolean flag that indicates whether this element contains data.
     * @return
     */
    public String getXhtmlFormElement(ResultSet rs, boolean isEmpty);

    /**
     * Tries to validate the given value.
     * @param value the value as a String.
     * @return the correct value.
     * @throws IOCException
     */
    public String validate(String value) throws IOCException;

    /**
     * Formats the given value, so it can be used in a SQL command.
     * @param value the value as a String.
     * @return
     * @throws IOCException
     */
    public String formatSQLValue(String value) throws IOCException;
}
